HealthQuantitySample# PRO

The HealthQuantitySample class represents a single health quantity data point, such as a heart rate measurement, a recorded step count, or a logged calorie value. It provides information about the measurement’s type, time interval, unit, value, and optional metadata.

This class is the base for more specialized subclasses: HealthCumulativeQuantitySample and HealthDiscreteQuantitySample.

#Overview

A HealthQuantitySample encapsulates the following:

• A specific health metric (e.g., steps, heart rate)
• A value with unit
• A time window representing when the data was recorded
• Optional metadata for context or classification

This class is primarily used for:

• Reading individual health data samples
• Writing new health data samples
• Converting values between units

#Properties

#Methods

#quantityValue(unit: HealthUnit): number

Converts the sample's stored value to the specified unit.

Parameters:

• unit: A HealthUnit instance (e.g., HealthUnit.kilocalorie())

Returns:

• The converted numeric value.

Example:

const bpm = sample.quantityValue(HealthUnit.count().divided(HealthUnit.minute()));
console.log(`Heart Rate: ${bpm} bpm`);

#Static Methods

#HealthQuantitySample.create(options): HealthQuantitySample | null

Creates a new quantity sample with the specified parameters.

Parameters:

{
  type: HealthQuantityType
  startDate: Date
  endDate: Date
  value: number
  unit: HealthUnit
  metadata?: Record<string, any> | null
}

Returns:

• A new HealthQuantitySample if valid, otherwise null.

Example:

const sample = HealthQuantitySample.create({
  type: "stepCount",
  startDate: new Date("2025-07-01T09:00:00"),
  endDate: new Date("2025-07-01T09:01:00"),
  value: 200,
  unit: HealthUnit.count(),
  metadata: { source: "manualEntry" },
});

#Subclass: HealthCumulativeQuantitySample

The HealthCumulativeQuantitySample class represents cumulative data (i.e., totals over time), such as energy burned or distance traveled.

#Additional Properties

#Additional Methods

#sumQuantity(unit: HealthUnit): number

Returns the total accumulated quantity in the specified unit.

Example:

const totalKcal = cumulativeSample.sumQuantity(HealthUnit.kilocalorie());
console.log(`Total active energy: ${totalKcal} kcal`);

#quantityValue(unit: HealthUnit): number

Alias for sumQuantity() — retrieves the total value in the given unit.

#Subclass: HealthDiscreteQuantitySample

The HealthDiscreteQuantitySample class represents a series of discrete values sampled at specific times — such as heart rate measurements or step counts across a time window.

#Additional Properties

#Additional Methods

#Example:

const avg = discreteSample.averageQuantity(HealthUnit.count());
const max = discreteSample.maximumQuantity(HealthUnit.count());
const recent = discreteSample.mostRecentQuantity(HealthUnit.count());
console.log(`Average: ${avg}, Max: ${max}, Recent: ${recent}`);

#Use Cases

#Related Types

• HealthUnit: Represents the unit of measurement.
• HealthQuantityType: Specifies the kind of health metric being measured.
• HealthDateInterval: A time range used for timestamping specific values.